home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / gfx / board / ShowJPEG15.lha / ShowJPEG.doc < prev    next >
Text File  |  1995-02-02  |  10KB  |  341 lines
  1.  
  2.  
  3.             =========================
  4.  
  5.                  ShowJPEG V1.5
  6.  
  7.             =========================
  8.  
  9.  
  10.                   2. Feb., 1995
  11.  
  12.  
  13.           Copyright (c) 1994/95 by Roman Hiestand
  14.  
  15.  
  16.  
  17.  
  18.  
  19. Copyright notice
  20. ----------------
  21.  
  22. The program ShowJPEG and its documentation are written and copyrighted by
  23. Roman Hiestand. They may be distributed freely providing the following
  24. restrictions are satisfied:
  25.  
  26. - Distributors may not charge more than the cost of a diskette used in
  27.   the distribution of this program.
  28.  
  29. - Distributors may only distribute the unmodified copy of the original
  30.   program, along with it's documentation, and copyright notices intact.
  31.  
  32. - Commercial  distribution  is  only  possible with written permission
  33.   from the author.
  34.  
  35.  
  36. Disclaimer
  37. ----------
  38.  
  39. This program and its documentation is provided "as is". No warranties are made
  40. with respect to the accuracy, reliability, performance or operation of this
  41. software and information. You are using this program at your own risk. The
  42. author is not liable for any damages that may have been caused by using this
  43. software.
  44.  
  45.  
  46.  
  47. Introduction
  48. ------------
  49.  
  50. It is done ! After hours and hours of hacking, debugging and #@©°!*-ing,
  51. this peace of software is ready to distribute:
  52.  
  53.                 ShowJPEG
  54.  
  55. the successor to the world-famous (:-) ShowGIF.
  56. I always wanted to replace the ViewJPEG delivered with the picasso-board,
  57. because it is buggy, incomplete and slow. But, you can believe me, jpeg
  58. is a tough and complicated topic. So I decided not to rewrite the whole
  59. thing but simply use the jpeg link-library from the independent JPEG
  60. software group. It is fairly quick and customizable, but it's big...
  61. That's why the program is quite large.
  62.  
  63.  
  64. Features
  65. --------
  66.  
  67.  - As compatible to the jpeg-standard as software can be
  68.  - Supports greyscaled pictures
  69.  - Various speed/quality tradeoff settings
  70.  - Fast
  71.  - CLI or WB start
  72.  - Can be aborted anytime (with Ctrl-C or Escape)
  73.  - Filerequester (since V1.2)
  74.  - Pattern matching (since V1.3)
  75.  - Nocrop option (since V1.4)
  76.  - Backdrop-screen (since V1.5)
  77.  
  78. Usage
  79. -----
  80.  
  81. From CLI: ShowJPEG File [...]
  82. From WB : via default tool or extended selection
  83.  
  84. Template:
  85. FILE/M,Q=QUALITY/K,SC=SCALE/N,DELAY/N,GRAY=GREY/S,VERBOSE/S,
  86.   8BIT/S,16BIT/S,24BIT/S,NOCENTER/S,ALL/S,NC=NOCROP/S,BEHIND/S
  87.  
  88. The options are accessible from CLI or Workbench.
  89.  
  90.  FILES/M    One or more filenames
  91.         Example: ShowJPEG DF0:Pictures/Tron.JPEG
  92.  
  93.  Q=QUALITY/K    The quality, one of BEST, NORMAL [default] or FAST.
  94.         BEST is always the best it can do, NORMAL is what I
  95.         considered as good enough but not too slow, and FAST
  96.         is always the fastest.
  97.         For more information see below.
  98.         Examples: ShowJPEG Tron.JPEG Q=BEST
  99.               ShowJPEG Tron.JPEG QUALITY BEST
  100.               ShowJPEG Tron.JPEG Q FAST
  101.         Default: NORMAL
  102.  
  103.  SC=SCALE/N    The scale factor, one of 1, 2, 4 or 8 (-> 1/1, 1/2..).
  104.         If you want to see a very large picture in whole or
  105.         you want to have just a quick preview, use scale.
  106.         Example: ShowJPEG BigPicture.jpg SCALE 2
  107.              ShowJPEG VeryBigPicture.jpg SC=8
  108.         Default: 1
  109.  
  110.  DELAY/N    Waits n seconds after displaying the picture.
  111.         Example: ShowJPEG Slideshow/*.jpg DELAY=5
  112.         Default: off
  113.  
  114.  GRAY=GREY/S    Displays the picture in grayscale. Use this if you
  115.         want to have a quick preview.
  116.         Example: ShowJPEG SlowPicture.jpg GREY
  117.         Default: off
  118.  
  119.  VERBOSE/S    Prints out information about the picture:
  120.         Width x Height x Depth of the picture ->
  121.         Width x Height x Depth of the screen
  122.         Example: ShowJPEG VERBOSE Pic.jpg
  123.         Default: off
  124.  
  125.  8BIT/16BIT/24BIT
  126.         Use these options if you want the picture displayed
  127.         in a certain screen depth. If it doesn't fit the
  128.         screen it's being cropped.
  129.         Example: ShowJPEG 24BIT LargePicture.jpeg
  130.         Default: off, this means the screen is chosen such
  131.         that the whole image fits the screen. If the image
  132.         is larger than the largest 8-Bit-screen the image
  133.         is cropped.
  134.  
  135.  NOCENTER/S    Don't display the picture in the center of the
  136.         screen.
  137.         Default: off
  138.  
  139.  ALL/S        Searches all subdirectories for the supplied
  140.         pattern (see also: Pattern matching).
  141.         Default: off
  142.  
  143.  NC=NOCROP/S    Simply put: if you set NOCROP, your picture won't
  144.         be cropped. It will be scaled, if necessary. If you
  145.         supply also the display depth, this one will be used.
  146.         If you didn't supply a depth, then after each scale-
  147.         step the depth will be reconsidered, meaning: it 
  148.         choses the highest possible depth for the scaled
  149.         picture (If this explanation confused you, try
  150.         it out with VERBOSE set).
  151.         Example: ShowJPEG 24BIT LargePicture.jpeg
  152.         This LargePicture will be scaled until it fits a
  153.         24 bit resolution.
  154.         Default: off
  155.  
  156.   BEHIND/S    This option opens a screen behind. It is only
  157.         useful for displaying multiple pictures.
  158.         After the first picture, ViewJPEG opens a
  159.         backdrop screen with the same ModeID.
  160.         This may help avoid 'flickering' due to
  161.         different screen modes of the Workbench and the
  162.         picture screen. But: it uses up a lot of memory,
  163.         because the same ModeID requests the same depth
  164.         and the same size of the screen.
  165.         Default: off
  166.  
  167. Every combination is possible:
  168.  
  169.  ShowJPEG QUALITY BEST DF0:Pictures/Tron.jpeg
  170.  ShowJPEG Q=FAST DH0:Art/MonaLisa.jpg
  171.  ShowJPEG DF0:Pictures/Tron.jpg 24BIT
  172.  ShowJPEG 8BIT DH0:Art/WindyDay.jpg DELAY 10 GREY VERBOSE
  173.  
  174. From Workbench:
  175. ShowJPEG reads it's own tooltypes and takes them as its
  176. defaults. It reads the tooltypes of every picture and uses
  177. these options, but they are switched back for the next
  178. picture.
  179.  
  180. Ctrl-C is now handled more correctly. You can break the whole
  181. program by typing Ctrl-C into the picture while it is being
  182. decoded. You can't break the program in the CLI !
  183. Since V1.5 you can now use Escape, too.
  184.  
  185.  
  186. The Quality setting
  187. -------------------
  188.  
  189. For those of you who know the jpeg-software:
  190.     - BEST means: Fancy upsampling
  191.       if quantizing: two pass quantize, Floyd-Steinberg dithering
  192.     - NORMAL means: normal upsampling
  193.       one pass quantize, ordered dithering
  194.     - FAST means: normal upsampling
  195.       one pass quantize, no dithering
  196.  
  197. In true/high color mode, the quality setting won't affect too much.
  198. But if the software has to reduce to 8 bits, the quality gain is very
  199. big: FAST is just a quick preview, NORMAL is not much slower but a quite
  200. good picture and BEST is what you could expect from any graphics
  201. software but is slow. (Anyway, BEST is ~3 times faster than ImageFX and
  202. gives similar results !)
  203. In BEST mode it (normally) uses a temporary file in T:, so don't set this
  204. to RAM: unless you have >2 Megs of free RAM.
  205.  
  206.  
  207. Pattern Matching
  208. ----------------
  209. (NB: * only works if you use WildStar or a similar program. Use #?
  210. instead)
  211.  
  212. Since V1.3 pattern matching is implemented. As this is a complex matter
  213. and it's not really the same in every program, I describe it in this
  214. chapter.
  215. ShowJPEG splits your supplied pattern into two parts:
  216.  
  217.     ShowJPEG    DF0:Pictures/*.jpg
  218.             | Path      || pattern \
  219.  
  220.  - The easy case: the path is not a pattern
  221.    ShowJPEG just searches the pattern in the supplied path and displays
  222.    every picture found.
  223.    Example: ShowJPEG DF0:Pictures/*.jpg
  224.     displays every picture in DF0:Pictures with .jpg at the end.
  225.         ShowJPEG DF0:Pictures/A*
  226.     displays every picture in DF0:Pictures starting with A or a.
  227.  
  228.    If you add 'ALL', the supplied path is taken as a starting point.
  229.    Every subdirectory is now searched for the pattern.
  230.    Example: ShowJPEG DF0:*.jpg ALL
  231.     displays every picture in DF0: and its subdirectories with
  232.     .jpg at the end.
  233.  
  234.  - The complex case: the path is a pattern
  235.    ShowJPEG searches now every path that matches the path pattern for
  236.    the file pattern.
  237.    The same with 'ALL', but now every subdirectory is searched too.
  238.    Example: ShowJPEG DH0:G*/A*.jpg
  239.     displays every picture in DH0:Graphics, DH0:Games ...
  240.     that matches A*.jpg (A at the beginning and .jpg at the end)
  241.         ShowJPEG DH0:G*/A*.jpg
  242.     displays every picture in all subdirectories of DH0:Graphics,
  243.     DH0:Games ... that matches A*.jpg
  244.         ShowJPEG DH0:G*/*.jpg
  245.     displays every .jpg picture in every subdirectory of
  246.     every directory starting with DH0:G (this can be a lot !)
  247.  
  248.  
  249. Of course, every standard pattern matching characters can be used:
  250.   ?  Matches any single character
  251.   #  Matches zero or more of the following character
  252.   |  Separates OR clauses
  253.   *  Matches any number of arbitrary characters (only with WildStar)
  254.  
  255. Examples:
  256.  - *.jpg matches Tron.jpg, Picture.jpg
  257.  - #a.jpg matches .jpg, a.jpg, aa.jpg, aaa.jpg ...
  258.  - A* matches Ape.jpg, a.jpg, Amiga.jpg (but also: Amiga.jpg.info !)
  259.  - a(b|c).jpg matches ab.jpg and ac.jpg
  260.  
  261. Pattern matching is NOT case sensitive.
  262.  
  263.  
  264. Requirements
  265. ------------
  266.  
  267. Kick 2.0 and vilintuisup.library version > 2.0.
  268.  
  269.  
  270. Bugs
  271. ----
  272.  
  273.  - Message window at WB-start disappears too quickly
  274.  
  275. I tested the program with various JPEG-pictures and with Enforcer on my 
  276. A3000. No misbehaviour could be found. But on different computer-systems
  277. with different environments, nobodoy knows what's gonna happen...
  278. If you find a bug, please report it to me together with as much information
  279. as possible that could help me to fix it: your computer, configuration, kick
  280. version and so on.
  281.  
  282.  
  283. Thanks
  284. ------
  285.  
  286. My thanks go to:
  287.  
  288.  - VillageTronic for their wonderful card
  289.  - the developers of the GNU-C-compiler and libnix
  290.  - the Independent JPEG Group for their software
  291.  
  292.  
  293. Future plans
  294. ------------
  295.  
  296.  - ??
  297.  
  298. Tell me if you want to have more options !
  299.  
  300.  
  301. Revisions
  302. ---------
  303.  
  304.     1.0    -    first public release
  305.  
  306.     1.1    -    Added NOCENTER
  307.             Remark: different default behaviour, it displays
  308.             now a picture in the center of the screen
  309.             (requested by Stefan Hülswitt)
  310.  
  311.     1.2    -    Added Filerequester
  312.             When no picture could be loaded, a file requester
  313.             pops up
  314.  
  315.     1.3    -    Added Pattern matching
  316.             Handles Ctrl-C better
  317.  
  318.     1.4    -    Added NOCROP option, rewrote OpenScreen code
  319.             (requested by Stefan Huelswitt and Antti Miettinen)
  320.             Corrected small bug (grey picture handling)
  321.             Compiled with gcc 2.6.3
  322.             Linked with jpeg library 5a and libnix 0.7
  323.  
  324.     1.5    -    Escape behaves now like Ctrl-C
  325.             Added BEHIND option (requested by Henning Sauer)
  326.  
  327.  
  328. Address
  329. -------
  330.  
  331. I can be reached at
  332.  
  333. Roman Hiestand
  334. Luziaweg 15
  335. CH-8807 Freienbach
  336. Switzerland
  337.  
  338. Fax: CH-055/48 26 37
  339.  
  340. email: rhiestan@iiic.ethz.ch
  341.